package com.srmt.user.api;

import com.srmt.user.exception.UserServiceException;
import java.util.List;
import java.util.Map;

/**
 * 用户ID解析器接口
 * 提供通过各种标识符获取用户ID的能力
 * 
 * @author SRMT Development Team
 * @since 1.0.0
 */
public interface UserIdResolver {
    
    /**
     * 通过电话号码获取用户ID
     * 
     * @param phoneNumber 电话号码，支持多种格式：
     *                    - 纯数字：13800138000
     *                    - 带国家码：+86-13800138000
     *                    - 带空格：+86 138 0013 8000
     * @return 用户ID，如果未找到返回null
     * @throws UserServiceException 查询失败时抛出
     */
    String getUserIdByPhone(String phoneNumber) throws UserServiceException;
    
    /**
     * 批量通过电话号码获取用户ID
     *
     * @param phoneNumbers 电话号码列表，支持多种格式
     * @return Map，key为电话号码，value为用户ID。如果某个号码未找到用户，则不包含在返回Map中
     * @throws UserServiceException 查询失败时抛出
     * @since 1.5.0
     */
    Map<String, String> getUserIdsByPhones(List<String> phoneNumbers) throws UserServiceException;

    /**
     * 通过电话号码或邮箱地址获取用户ID
     * 自动识别标识符类型（电话或邮箱）并进行相应的查询
     *
     * @param identifier 电话号码或邮箱地址，支持多种格式：
     *                   电话 - 纯数字：13800138000
     *                        - 带国家码：+86-13800138000
     *                        - 带空格：+86 138 0013 8000
     *                   邮箱 - 标准格式：user@example.com
     *                        - 大小写不敏感
     * @return 用户ID，如果未找到返回null
     * @throws UserServiceException 查询失败时抛出
     * @throws com.srmt.user.exception.InvalidIdentifierException 标识符格式无效时抛出
     * @since 1.7.0
     */
    String getUserIdByPhoneOrEmail(String identifier) throws UserServiceException;

    /**
     * 批量通过电话号码或邮箱地址获取用户ID
     * 支持电话和邮箱混合列表，自动识别每个标识符的类型并进行相应的查询
     *
     * @param identifiers 电话号码或邮箱地址列表，支持混合
     * @return Map，key为原始标识符，value为用户ID。如果某个标识符未找到用户，则不包含在返回Map中
     * @throws UserServiceException 查询失败时抛出
     * @throws com.srmt.user.exception.InvalidIdentifierException 某个标识符格式无效时抛出
     * @since 1.7.0
     */
    Map<String, String> getUserIdsByPhoneOrEmail(List<String> identifiers) throws UserServiceException;
}